home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / UNIXTOOL / GNU / GNUDBM / GNUDBM~ / <tarZ$use> / files / GNUDbm / Readme < prev   
Text File  |  1989-07-03  |  9KB  |  265 lines
  1. This is the initial release of GNU dbm.  Better documentation will
  2. be written soon.  For now, this file briefly describes the contents
  3. of this release and how to use it.
  4.  
  5. The files are:
  6.  
  7. COPYING        - Copying information.
  8. README        - This file
  9. bucket.c, dbminit.c, delete.c, extern.h, falloc.c, fetch.c, findkey.c,
  10. gdbm.h, gdbmclose.c, gdbmdelete.c, gdbmerrno.h, gdbmfetch.c,
  11. gdbmopen.c, gdbmreorg.c, gdbmseq.c, gdbmstore.c, global.c, hash.c
  12. seq.c, store.c, update.c  -  Source for GNU dbm library.
  13. Makefile     - Makefile, will make gdbm.a 
  14. test.c        - A simple test program.
  15. version.c    - The current version number in a string.
  16.  
  17.  
  18. GNU dbm is a set of database routines that use extendible hashing and
  19. works similar to the standard UNIX dbm routines.  The basic unit of
  20. data is the structure
  21.  
  22.   typedef struct {
  23.              char *dptr;
  24.              int   dsize;
  25.           } datum;
  26.  
  27. The following is a quick list of the routines.  After this list, a
  28. longer description of each routine will be given.  The routines are:
  29.  
  30.   char *gdbm_open ( name, block_size, read_write, fatal_func )
  31.  
  32.   gdbm_close ( dbf )
  33.   
  34.   int gdbm_store ( dbf, key, content )
  35.  
  36.   datum gdbm_fetch ( dbf, key )
  37.  
  38.   int gdbm_delete ( dbf, key )
  39.  
  40.   datum gdbm_firstkey ( dbf )
  41.  
  42.   datum gdbm_nextkey ( dbf, key )
  43.  
  44.   int gdbm_reorganize ( dbf )
  45.  
  46.   gdbm_recovery ( dbf, state )
  47.  
  48. For compatibility with the standard dbm, the following routines are 
  49. defined.
  50.  
  51.   int dbminit ( name )
  52.  
  53.   int store ( key, content )
  54.  
  55.   datum fetch ( key )
  56.  
  57.   int delete ( key )
  58.  
  59.   datum firstkey ()
  60.  
  61.   datum nextkey ( key )
  62.  
  63. An additional routine is needed for use with the compatibility routines.
  64.  
  65.   dbmclose ()
  66.  
  67.  
  68.  
  69.  
  70. Description of GNU dbm routines.
  71. --------------------------------
  72.  
  73. GNU dbm allows multiple data files.  A routine that opens a gdbm file
  74. is designated as a "reader" or a "writer".  Only one writer may open a
  75. gdbm file and many readers may open the file.  Readers and writers can
  76. not open the gdbm file at the same time. The procedure for opening a
  77. gdbm file is:
  78.  
  79. char * dbf;
  80.  
  81. dbf = gdbm_open ( name, block_size, read_write, fatal_func )
  82.  
  83. The parameters are:
  84.   char *name - the name of the file (the complete name, gdbm does
  85.       not append any characters to this name)
  86.   int block_size - the size of a single transfer from disk to memory.
  87.       This parameter is ignored unless the file is a new file.
  88.       The minimum size is 512.  If it is less than 512, dbm will
  89.       use the stat block size for the file system.
  90.   int read_write - 0 => reader, 1 => writer
  91.   void (*fatal_func) () - a function for dbm to call if it detects a
  92.       fatal error. The only parameter of this function is a string.
  93.       If the value of 0 is provided, dbm will use a default function.
  94.  
  95. The return value, dbf, is the pointer needed by all other routines to
  96. access that gdbm file.  If the return is the NULL pointer, gdbm_open
  97. was not successful.  The errors can be found in "gdbm_errno" for gdbm
  98. errors and in "errno" for file system errors.  (For error codes, see
  99. gdbmerrno.h.)
  100.  
  101. In all of the following calls, the parameter "dbf" refers to the pointer
  102. returned from gdbm_open.
  103.  
  104. It is important that every file opened is also closed.  This is needed to
  105. update the reader/writer count on the file.  This is done by:
  106.  
  107.   gdbm_close(dbf);
  108.  
  109.  
  110. The database is used by 3 primary routines.  The first stores data in the
  111. database.
  112.  
  113.   ret = gdbm_store ( dbf, key, content )
  114.  
  115.   The parameters are:
  116.      char *dbf - the pointer returned by gdbm_open
  117.      datum key - the key data
  118.      datum content - the data to be associated with the key
  119.  
  120.   If a reader calls store, ret gets -1.  Otherwise, ret is 0.
  121.   NOTICE: If you store data for a key that is already in the data base,
  122.   gdbm replaces the old data with the new data.  You do not get two
  123.   data items for the same key and you do not get an error from gdbm_store.
  124.  
  125. To search for some data:
  126.  
  127.   content = gdbm_fetch ( dbf, key )
  128.  
  129.   The parameters are:
  130.      char *dbf - the pointer returned by gdbm_open
  131.      datum key - the key data
  132.  
  133.   The "datum" returned in content is a pointer to the data found.  If the
  134.   dptr is NULL, no data was found.  If dptr is not NULL, then it points
  135.   to data allocated by malloc.  gdbm does not automatically free this data.
  136.   The user must free this storage when done using it.  This eliminates the
  137.   need to copy the result to save it for later use. (You just save the 
  138.   pointer.)
  139.  
  140. To remove some data from the database:
  141.  
  142.   ret = gdbm_delete ( dbf, key )
  143.  
  144.   The parameters are:
  145.      char *dbf - the pointer returned by gdbm_open
  146.      datum key - the key data
  147.  
  148.   The ret value is -1 if the item is present or the requester is a reader.
  149.   The ret value is 0 if there was a successful delete.
  150.  
  151.  
  152. The next two routines allow for accessing all items in the database.  This 
  153. access is not key sequential, but it is guaranteed to visit every key in
  154. the database once.  (The order has to do with the hash values.)
  155.  
  156.   key = gdbm_firstkey ( dbf )
  157.  
  158.   nextkey = gdbm_nextkey ( dbf, key )
  159.  
  160.   The parameters are:
  161.      char *dbf - the pointer returned by gdbm_open
  162.      datum key - the key data
  163.  
  164.   The return values are both datum.  If key.dptr or nextkey.dptr is NULL,
  165.   there is no first key or next key.  Again notice that dptr points to
  166.   data allocated by malloc and gdbm will not free it for you. 
  167.  
  168. The following routine should be used very seldom.  
  169.   
  170.   ret = gdbm_reorganize ( dbf )
  171.  
  172.   If you have had a lot of deletions and would like to shrink the space
  173.   used by the gdbm file, the this routine will reorganize the database.
  174.   gdbm will not shorten the length of a gdbm file except by using this
  175.   reorganization.  (Deleted file space will be reused.)
  176.  
  177. Finally, gdbm does crash detection and recovery.  This causes a little
  178. overhead in processing of the gdbm_store and gdbm_delete routines.  If
  179. crash detection and recovery are unimportant or costs too much, you can
  180. turn off crash detection and recovery.  This is done on an individual
  181. file basis.  It remains off until a request is made to turn it on again.
  182. The following routine changes the state of crash detection and recovery:
  183.  
  184.   gdbm_recovery ( dbf, state )
  185.  
  186.   The parameters are:
  187.      char *dbf - the pointer returned by gdbm_open
  188.      int  state - 0 to turn it off, anything else to turn on.
  189.  
  190.  
  191. The following two are variables that may need to be used:
  192.  
  193.   gdbm_error gdbm_errno   -   the variable that contains more information
  194.                               about gdbm errors.
  195.  
  196.   char * gdbm_version     -   the string containing the version information.
  197.  
  198.  
  199. There are a few more things of interest.  First, gdbm files are not
  200. "sparse".  You can copy them with the UNIX cp command and they will
  201. not expand in the copying process.  Also, there is a compatibility
  202. mode for use with programs that already use UNIX dbm.  In this
  203. compatibility mode, no gdbm file pointer is required by the user.
  204. Only one file may be opened at a time.  All users in compatibility
  205. mode are assumed to be writers.  Also, default crash detection and
  206. recovery is turned off for compatibility mode.  All returned pointers
  207. in datum structures point to data that gdbm WILL free.  They should be
  208. treated as static pointers (as standard UNIX dbm does).  The
  209. compatibility routine names are the same as the UNIX dbm routine
  210. names.  Their definitions follow:
  211.  
  212.   int dbminit ( name )
  213.  
  214.   int store ( key, content )
  215.  
  216.   datum fetch ( key )
  217.  
  218.   int delete ( key )
  219.  
  220.   datum firstkey ()
  221.  
  222.   datum nextkey ( key )
  223.  
  224. An additional routine is needed for use with the compatibility routines.  This
  225. closes the database file.  Adding this routine should be the only change
  226. to programs using the standard UNIX dbm.
  227.  
  228.   dbmclose ()
  229.  
  230.  
  231. WARNING: standard UNIX dbm and GNU dbm do not have the same data format in the
  232. file.  You cannot access a standard UNIX dbm file with GNU dbm!
  233.  
  234.  
  235.  
  236.  
  237. Notes on making GNU dbm.
  238. ------------------------
  239.  
  240. The "Makefile" will make both "gdbm.a", the collection of gdbm routines and
  241. a simple test program that uses the gdbm routines.  There are three make
  242. commands:
  243.    make gdbm.a        makes the gdbm.a archive.
  244.    make test        makes both gdbm.a and the test program.
  245.    make install        installs gdbm.a as /usr/lib/libgdbm.a.
  246.  
  247. The makefile is distributed with RANDOM_HASH defined.  This causes the
  248. hash function in gdbm to use the UNIX random function to produce a well
  249. distributed and random hash value.  If this computation is too costly
  250. for you, you can remove the definition of RANDOM_HASH from the makefile.
  251. WARNING:  GNU dbm compiled with RANDOM_HASH will not read databases
  252. created by GNU dbm compiled without RANDOM_HASH!
  253.  
  254. Also, similar to UNIX dbm, GNU dbm will not create a gdbm file.  If it
  255. finds a file with zero length, ti will initialize the file.  To make
  256. a new gdbm database file, "touch file.name" and then run the program
  257. that opens "file.name" as a gdbm file.  The first execution will
  258. initialize the file.
  259.  
  260. Please send bug reports to phil@wwu.edu.
  261.  
  262. Thank you.
  263.  
  264.  
  265.